Skip to content

Feature/doc modernization#3566

Merged
jmprieur merged 40 commits intomasterfrom
feature/doc-modernization
Jan 3, 2026
Merged

Feature/doc modernization#3566
jmprieur merged 40 commits intomasterfrom
feature/doc-modernization

Conversation

@jmprieur
Copy link
Collaborator

@jmprieur jmprieur commented Oct 20, 2025

Microsoft.Identity.Web doc modernization (in progress)

jmprieur and others added 11 commits October 5, 2025 21:13
…3535)

* Initial plan

* Add core sidecar documentation files

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* Add remaining core documentation files

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* Add all scenario documentation files

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* Address PR feedback: Convert diagram to mermaid, update wording, add validation scenario

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* Update docs/sidecar/reverse-proxy.md

* Address PR review feedback: Update agent identity docs, improve examples, fix terminology

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* Update docs/sidecar/faq.md

* Replace ASCII diagram with mermaid diagram in comparison.md

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Keegan <Keegan.Caruso@microsoft.com>

* Update docs/sidecar/comparison.md

* Update docs/sidecar/comparison.md

* Address comprehensive PR review feedback

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* Remove Service Mesh Integration section from security.md

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* Update network security guidance to use Kestrel configuration instead of network policies

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* Add input validation guidance and incident response plan reference

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>
Co-authored-by: Jean-Marc Prieur <jmprieur@microsoft.com>
Co-authored-by: Keegan <Keegan.Caruso@microsoft.com>
…tion (#3564)

* Initial plan

* Streamline sidecar documentation with table format and remove duplication

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* Update Microsoft documentation URLs to current learn.microsoft.com domain

Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>

* docs(sidecar): fix endpoints path formatting and clarify wording

* Revise README for clarity and improved navigation

Updated the README to enhance clarity and structure, including new sections and improved descriptions for scenarios and resources.

* Revise Entra Identity Sidecar documentation

Updated the Microsoft Entra Identity Sidecar documentation to enhance clarity and detail on token acquisition, validation, and integration. Added benefits and use cases for the sidecar approach.

* Update endpoints.md

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jmprieur <13203188+jmprieur@users.noreply.github.com>
Co-authored-by: Jean-Marc Prieur <jmprieur@microsoft.com>
@jmprieur jmprieur requested a review from a team as a code owner October 20, 2025 00:55
@jmprieur jmprieur marked this pull request as draft October 20, 2025 00:56
* Downstream Apis

* Update README.md with revised service registration pattern and documentation improvements.

* Revise README for Calling Downstream APIs

This document provides a comprehensive guide for implementing various approaches to call downstream APIs using Microsoft.Identity.Web, including decision trees, comparison tables, token acquisition patterns, and code examples for different scenarios.

* Enhance README for downstream API guidance

Updated README to include .NET applications and agent identities.

* Update README with API selection decision table

Replaced mermaid diagram with a decision table for API selection.

* Update docs/calling-downstream-apis/azure-sdks.md

* Refactor downstream API documentation

Updated the documentation for calling downstream APIs by consolidating API registration and clarifying the request methods. Removed redundant sections and improved the structure.

* Remove Azure SDK examples from documentation

Removed examples for Azure KeyVault, Azure Storage Blobs, Azure KeyVault Secrets, Azure Service Bus, Azure Tables, and Azure Cosmos DB from the documentation.

* Update custom-apis.md

* Update from-web-apis.md

* Update microsoft-graph.md
Updated the documentation modernization plan with completed milestones and revised priorities. Adjusted documentation structure and clarified the status of various sections, including the addition of new documentation for sidecar and agent identities.
@jmprieur jmprieur marked this pull request as ready for review December 3, 2025 22:24
sarahsa pushed a commit to heimdallpower/api-sdk that referenced this pull request Feb 3, 2026
Updated
[Microsoft.Extensions.Http.Resilience](https://github.com/dotnet/extensions)
from 9.9.0 to 9.10.0.

<details>
<summary>Release notes</summary>

_Sourced from [Microsoft.Extensions.Http.Resilience's
releases](https://github.com/dotnet/extensions/releases)._

## 9.10.0

## What's Changed
* Branding updates for 9.10 by @​Copilot in
dotnet/extensions#6769
* Doc improvements by @​gewarren in
dotnet/extensions#6794
* Bump vite from 6.3.5 to 6.3.6 in
/src/Libraries/Microsoft.Extensions.AI.Evaluation.Reporting/TypeScript
by @​dependabot[bot] in dotnet/extensions#6793
* Updated changelogs for AI libs by @​stephentoub in
dotnet/extensions#6787
* Update MCP server template by @​jeffkl in
dotnet/extensions#6772
* Add support for using ConversationID for AzureOpenAI and OpenAI by
@​ViveliDuCh in dotnet/extensions#6770
* Merging internal commits by @​joperezr in
dotnet/extensions#6801
* Merge changes from release/9.9 branch by @​joperezr in
dotnet/extensions#6803
* Support keyed HybridCache with keyed DistributedCaches and named
options by @​kelly-yinn in
dotnet/extensions#6694
* Inventory as code by @​wtgodbe in
dotnet/extensions#6820
* Increase output token limit for EquivalenceEvaluator by
@​shyamnamboodiripad in dotnet/extensions#6835
* Fix KeyNotFoundException on HttpRequestLatencyListener.OnEventWritten
for uknown event sources by @​ssmelov in
dotnet/extensions#6821
* Add project name normalization to match aspire's code generator logic
by @​ViveliDuCh in dotnet/extensions#6818
* Disable really noisy analyzers, part 1 by @​stephentoub in
dotnet/extensions#6837
* Fix `KeyNotFoundException` in
`HttpRequestLatencyListener.OnEventWritten` by @​pentp in
dotnet/extensions#6823
* Update global.json to use .NET 9.0.0 stable instead of RC 1 by
@​Copilot in dotnet/extensions#6846
* Add measures and tags with mediator object to the
HttpClientLatencyLogEnricher by @​rainsxng in
dotnet/extensions#6783
* Add comprehensive .github/copilot-instructions.md for
dotnet/extensions repository by @​Copilot in
dotnet/extensions#6792
* Update to .NET 10 SDK by @​eerhardt in
dotnet/extensions#6863
* Update Microsoft.Extensions.AI changelog files with current NuGet
versions by @​Copilot in dotnet/extensions#6849
* Fix GenerateImagesAsync_SingleImageGeneration integration test by
@​stephentoub in dotnet/extensions#6843
* Re-enable IDE0032 by @​stephentoub in
dotnet/extensions#6866
* Add OpenTelemetrySpeechToTextClient and friends by @​stephentoub in
dotnet/extensions#6845
* Update `ModelContextProtocol` version in MCP template by
@​MackinnonBuck in dotnet/extensions#6870
* Scope Ollama resilience settings to Web/Program.cs and restore
ServiceDefaults by @​ViveliDuCh in
dotnet/extensions#6850
* Update Aspire by @​Varorbc in
dotnet/extensions#6858
* Update MCP template for new registry specification by @​Copilot in
dotnet/extensions#6796
* Add support for `HostApplicationBuilder` in AmbientMetadata extension
by @​eduherminio in dotnet/extensions#6867
* Fix mcpserver test baselines by @​jeffhandley in
dotnet/extensions#6874
* Move Microsoft.Extensions.ServiceDiscovery to dotnet/extensions by
@​eerhardt in dotnet/extensions#6868
* Add copy constructors to option types (ChatOptions, etc.) by
@​stephentoub in dotnet/extensions#6882
* Fix ChatMessage.CreatedAt being always overwritten by the latest
timestamp. by @​Copilot in
dotnet/extensions#6885
* Small doc fixes by @​gewarren in
dotnet/extensions#6887
* Update AI changelogs with some recent additions by @​stephentoub in
dotnet/extensions#6886
* Fix Assistants IChatClient handling of unrelated tool calls in history
by @​stephentoub in dotnet/extensions#6891
* Fix duplication between OpenAI Assistants pre-configured tools by
@​stephentoub in dotnet/extensions#6896
* Update MCP Server Template to adhere to 2025-09-29 server.json schema
by @​joelverhagen in dotnet/extensions#6888
* Remove Azure.AI.OpenAI dependency from templates and tests by
@​Copilot in dotnet/extensions#6873
* Remove UnsafeRelaxedJsonEscaping by @​peterwald in
dotnet/extensions#6899
* Fix bug to yield remaining buffered FCC by @​westey-m in
dotnet/extensions#6903
* Fix serialization of [Experimental] AIContent-derived types by
@​stephentoub in dotnet/extensions#6900

## New Contributors
* @​westey-m made their first contribution in
dotnet/extensions#6745
* @​jeffkl made their first contribution in
dotnet/extensions#6772
* @​ViveliDuCh made their first contribution in
dotnet/extensions#6770
* @​kelly-yinn made their first contribution in
dotnet/extensions#6694
* @​ssmelov made their first contribution in
dotnet/extensions#6821
* @​Varorbc made their first contribution in
dotnet/extensions#6858
 ... (truncated)

Commits viewable in [compare
view](dotnet/extensions@v9.9.0...v9.10.0).
</details>

Updated
[Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web)
from 4.0.1 to 4.3.0.

<details>
<summary>Release notes</summary>

_Sourced from [Microsoft.Identity.Web's
releases](https://github.com/AzureAD/microsoft-identity-web/releases)._

## 4.3.0

### New features
- Added token binding (mTLS PoP) scenario for confidential client
(app-only) token acquisition and downstream API calls. See
[#​3622](AzureAD/microsoft-identity-web#3622).

### Dependencies updates
- Bumped **qs** from 6.14.0 to 6.14.1 in
/tests/DevApps/SidecarAdapter/typescript. See [#​3660](
AzureAD/microsoft-identity-web#3660).

### Documentation
- Modernized Identity Web documentation, which is now can be found in
[docs](https://github.com/AzureAD/microsoft-identity-web/tree/master/docs).
See
[#​3566](AzureAD/microsoft-identity-web#3566).
- Added token binding (mTLS PoP) documentation. See
[#​3661](AzureAD/microsoft-identity-web#3661).

## 4.2.0

# What's Changed

## New features

- Added CAE claims support for FIC + Managed Identity. See #​3647 for
details.
- Added AddMicrosoftIdentityMessageHandler extension methods for
IHttpClientBuilder. See #​3649 for details.

## Bug fixes


- Fixed tenant not being propagated in credential FIC acquisition. See
#​3633 for details.
- Fixed ForAgentIdentity hardcoded 'AzureAd' ConfigurationSection to
respect AuthenticationOptionsName. See #​3635 for details.
- Fixed GetTokenAcquirer to propagate MicrosoftEntraApplicationOptions
properties. See #​3651 for details.
- Added meaningful error message when identity configuration is missing.
See #​3637 for details.

## Dependencies updates

- Update Microsoft.Identity.Abstractions to version 10.0.0.
- Bump express from 5.1.0 to 5.2.0 in
/tests/DevApps/SidecarAdapter/typescript. #​3636
- Bump jws from 3.2.2 to 3.2.3 in
/tests/DevApps/SidecarAdapter/typescript. #​3641

## Fundamentals

- Update support policy. #​3656
- Update agent identity coordinates in E2E tests after deauth. #​3640
- Update E2E agent identity configuration to new tenant. #​3646


**Full Changelog**:
AzureAD/microsoft-identity-web@4.1.1...4.2.0

## 4.1.1

### Bug fixes
- Authority-only configuration parsing improvements: Early parsing of
Authority into Instance/TenantId and defensive fallback in
PrepareAuthorityInstanceForMsal. Behavior is backward compatible;
Authority is still ignored when Instance/TenantId explicitly
provided—now surfaced via a warning. See
[#​3612](AzureAD/microsoft-identity-web#3612).

### New features
- Added warning diagnostics for conflicting Authority vs
Instance/TenantId: Emitting a single structured warning when both styles
are provided. See
[#​3611](AzureAD/microsoft-identity-web#3611).

### Fundamentals
- Expanded authority test matrix: Coverage for AAD (v1/v2), B2C (/tfp/
normalization, policy path), CIAM (PreserveAuthority), query parameters,
scheme-less forms, and conflict scenarios. See
[#​3610](AzureAD/microsoft-identity-web#3610).

## 4.1.0

### New features
- Migrate to .NET 10 GA.
[#​3449](AzureAD/microsoft-identity-web#3449)
and
[#​3590](AzureAD/microsoft-identity-web#3590)

### Dependencies updates
- Bump MSAL.NET to version
[4.79.2](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/releases/tag/4.79.2)
and handle changes to deprecated WithExtraQueryParameters APIs.
[#​3583](AzureAD/microsoft-identity-web#3583)
- Update Microsoft.IdentityModel and Abstractions versions.
[#​3604](AzureAD/microsoft-identity-web#3604)
- Update coverlet.collector to 6.0.4.
[#​3587](AzureAD/microsoft-identity-web#3587)
- Update package validation baseline version to 4.0.0.
[#​3589](AzureAD/microsoft-identity-web#3589)
- Bump js-yaml from 4.1.0 to 4.1.1 in
/tests/DevApps/SidecarAdapter/typescript.
[#​3595](AzureAD/microsoft-identity-web#3595)

### Entra ID SDK sidecar
- Restrict hosts to localhost for sidecar.
[#​3579](AzureAD/microsoft-identity-web#3579)
- Update http file to match endpoints.
[#​3555](AzureAD/microsoft-identity-web#3555)
- Revise sidecar issue template for Entra ID.
[#​3577](AzureAD/microsoft-identity-web#3577)

### Documentation
- Update README to include Entra SDK container info.
[#​3578](AzureAD/microsoft-identity-web#3578)

### Fundamentals
- Include NET 9.0 in template-install-dependencies.
[#​3593](AzureAD/microsoft-identity-web#3593)
- Fix CodeQL alerts.
[#​3591](AzureAD/microsoft-identity-web#3591)
- Suppression file is needed.
[#​3592](AzureAD/microsoft-identity-web#3592)

Commits viewable in [compare
view](AzureAD/microsoft-identity-web@4.0.1...4.3.0).
</details>

Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore <dependency name> major version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's major version (unless you unignore this specific
dependency's major version or upgrade to it yourself)
- `@dependabot ignore <dependency name> minor version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's minor version (unless you unignore this specific
dependency's minor version or upgrade to it yourself)
- `@dependabot ignore <dependency name>` will close this group update PR
and stop Dependabot creating any more for the specific dependency
(unless you unignore this specific dependency or upgrade to it yourself)
- `@dependabot unignore <dependency name>` will remove all of the ignore
conditions of the specified dependency
- `@dependabot unignore <dependency name> <ignore condition>` will
remove the ignore condition of the specified dependency and ignore
conditions


</details>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants